Parent | Child | Previous | Next
 

JSON Syntax for OnSubmit

Description

The onSubmit event for Alpha TransForm can be used to trigger a variety of actions. The actions are defined using JSON. This article documents the JSON syntax for onSubmit actions.

Discussion

Actions for the onSubmit event are defined using the JSON document format.

You must escape double quotes (") in the onSubmit definition. This is done by including a leading backslash: \".

Event Types

The following actions are available:

Action
Description
Send Email

Send an email containing the submitted form data.

Report

Generate a report for the submitted form.

Call webhook

Submit the form data to another application or web service.

Send to SQL database

Save the form data to a SQL database.

Merge data into a PDF form

Merge the form data into a fillable PDF.

Dispatch/Route a form

Create a new form and assign it to the user who submitted the form, or assign the submitted form to another user.

  • Send an Email

    The Send an Email action sends an email containing the submitted form data. The form data can be sent as either JSON, HTML, or an Excel file. If sent as JSON or HTML, the form data is included in the body of the email message.

    [{
    "action": "SendEmail",
    "sendto": "[email protected]",
    "subject": "TransForm Data",
    "sendFormat": "JSON",
}]

    If no conditional filter is defined for the action, the Send an Email action will send an email for every form instance submitted to TransForm Central. The formIds property defines which forms types to email.

    [{
    "action": "SendEmail",
    "sendto": "[email protected]",
    "subject": "TransForm Data",
    "sendFormat": "JSON",
    "formIds": "Form2,equipment_inspection,Form2-1,InspectEquipment"
}]

    You can also define a condition condition expression to filter the forms that are emailed. For example:

    {
    "action": "SendEmail",
    "sendto": "[email protected]",
    "subject": "TransForm Data",
    "sendFormat": "JSON",
    "formIds": "Form2,equipment_inspection,Form2-1,InspectEquipment"
    "condition": "formdata.firsttime = \"Y\" .and. metadata.formid = \"form1\""
}

    • Send an Email Settings

      sendto

      The email address to send the email. Specify mulitple email addresses as a comma-delimited list. E.g. "[email protected],[email protected],[email protected]"

      subject

      The email subject.

      sendFormat

      The format to send the form data. Can be one of the following:

      sendFormat
      Description
      JSON

      Form data is embedded in the email body in JSON format.

      HTML

      Form data is embedded in the email body in HTML format.

      EXCEL

      Form data is attached to the email as an Excel file.

      formIds

      An optional comma-delimited list of form types. If not specified or set to "*", an email will be sent for every form submitted. Otherwise, only forms that are submitted that are of one of the types listed will be emailed.

      condition

      An optional condition expression that controls whether or not the email action should be executed. If the condition evaluates to true, the form data will be emailed. Otherwise, the form data will not be emailed. See Condition below for more information.

    • Condition

      The JSON definition for a Send an Email event can include an optional condition property. The condition property is a logical expression that controls whether or not the email should be sent.

      The condition expression can reference both form data fields and meta data fields.

      The expression must prefix form data fields with formdata. and meta data fields with metadata.. Example syntax is shown below:

      Test to see if the formdata "passed" field is set to "N"
      formdata.passed = "N"
      Test to see if the metadata "status" field is set to "closed" and the formdata passed "passed" field is set to "N"
      formdata.passed = "N" .and. metadata.status = "closed"
      Checks to see if the number of items in the "photos" Data Group is greater than 0 or metadata "status" field is set to "closed" and the formdata passed "passed" field is set to "N"
      (formdata.passed = "N" .and. metadata.status = "closed") .or. (formdata.photos.size() > 0)

      The following operators are allowed in the condition expression:

      =, <>, >, >=, <=

      Parenthesis can be used in the expression.

      The logical operators are:

      .and., .or., .not.

      The following functions are allowed in the Send an Email condition expression:

      • lower() - converts to lower case
      • ut() - converts to upper case and trims any trailing or leading spaces
      • upper() - converts to upper case
      • convert_type() - converts data to a specific type. Types are N, D, T, or L - (Numeric, Date, Date/time, Logical). It may be necessary to convert data for certain types of comparisons. e.g. convert_type(metadata.completed,"D:) = date() -- test to see if form was completed on today"s date.
      • size() - a method on a DataGroup to return the number of rows of data in the Data Group
      • day() - returns the day (as a number) of the month from a date value. e.g. day( convert_type(metadata.completed,"D"))
      • year() - returns the year (as a number) from a date value
      • month() - returns the month (as a number) from a date value
      • substr() - returns a portion of a text value. e.g. substr(formdata.name,1,3) - start at position 1 and return 3 characters
      • atc() - returns the position in a string where text is found - atc("p","alpha") = 3
      • at() - case sensitive version of atc()
      • occurs() - returns the number of occurrences of one string in another - occurs("a","alpha")
      • occursi() - case-insensitive version of occurs()
      • word() - returns the nth word in a string using the specified word delimiter. word("a,b,c",2,",") = "b" (using comma as the "word" delimiter)
      • wordi() - case insensitive version of word()

      Here is an example of a onSubmit event definition that will fire when "form1" is submitted if the "firstime" field in the form contains "Y":

      [{
        "action": "sendEmail",
        "sendTo": "[email protected]",
        "sendFormat": "json",
        "condition": "formdata.firsttime = \"Y\" .and. metadata.formid = \"form1\""
    }]

Accessing Form Metadata

Form metadata fields can be referenced in onSubmit actions in templates and conditional statements. The available meta data fields include:

accountid

The TransForm Account ID associated with the form instance. E.g. "Account001"

created

The date/time when the form was created.

comments

JSON representing the comments associated with the form instance. The value of comments is a string. For example:

"[{\"timestamp\":\"2019-06-10T19:36:38.102Z\",\"person\":\"Tanya\",\"text\":\"Please double-check occupancy count. 10 seems a bit high.\"},{\"timestamp\":\"2019-06-11T19:36:22.775Z\",\"person\":\"Leif\",\"text\":\"Count is correct. 10 cats on premise.\"}]"
completed

The date/time when the form status was last changed.

duedate

The due date for the form instance. This value is used by the Form Filler Filtering functionality. It should either be blank or a date in the form of "yyyy-mm-dd", such as "2019-04-19".

formid

The form type id. This is the id given when the form type was designed.

forminstanceid

The form instance id. This is a unique value assigned by Alpha TransForm.

formversion

The form version. This is currently unused.

haserrors

Whether or not the form contains errors. If the value of this field is "Y", the form contains errors. If the value is "" (blank), the form contains no errors.

missingrequired

Whether or not the form is missing required data. If the value of this field is "Y", the form has missing required data. If the value is "" (blank), the form has no missing require data.

nofiller

Whether or not the form should be removed from the TransForm App. If the value of this field is "Y", the form will be removed from the TransForm App and will not appear in any queues. If the value is "N" or "" (blank), the form will appear in the TransForm App for the user or queue the form is assigned.

person

The user ID of the person who is assigned the form instance.

status

The current status of the form instance. E.g. "submitted" or "closed".

timestamp

The date/time when the form instance was last updated (inserted or modified) in the TransForm Central database.

user1, user2, user3, user4, user5

User-defined fields. The data in these fields is set by the TransForm account administrator.

userlabel1, userlabel2, userlabel3, userlabel4, userlabel5

Labels for use-defined fields user1-user5. The data in these fields is set by the TransForm account administrator.